From 1fe5f9e97e58fc107f245199307f39fd681c60f1 Mon Sep 17 00:00:00 2001 From: "kaf24@firebug.cl.cam.ac.uk" Date: Thu, 9 Feb 2006 12:17:35 +0100 Subject: [PATCH] More details on ordering and safety of the Xen timer API. Most functions are safe to call after a timer structure has been initialised to all zeroes, as long as they are *never* called concurrently with init_timer(). Signed-off-by: Keir Fraser --- xen/include/xen/timer.h | 30 ++++++++++++++++++++---------- 1 file changed, 20 insertions(+), 10 deletions(-) diff --git a/xen/include/xen/timer.h b/xen/include/xen/timer.h index ed25521c1a..f0c9b7e8a5 100644 --- a/xen/include/xen/timer.h +++ b/xen/include/xen/timer.h @@ -30,15 +30,21 @@ struct timer { * All functions below can be called for any CPU from any CPU in any context. */ -/* Returns TRUE if the given timer is on a timer list. */ +/* + * Returns TRUE if the given timer is on a timer list. + * The timer must *previously* have been initialised by init_timer(), or its + * structure initialised to all-zeroes. + */ static __inline__ int active_timer(struct timer *timer) { return (timer->heap_offset != 0); } /* - * It initialises the static fields of the timer structure. - * It can be called multiple times to reinitialise a single (inactive) timer. + * Initialise a timer structure with an initial callback CPU, callback + * function and callback data pointer. This function may be called at any + * time (and multiple times) on an inactive timer. It must *never* execute + * concurrently with any other operation on the same timer. */ static __inline__ void init_timer( struct timer *timer, @@ -53,21 +59,23 @@ static __inline__ void init_timer( } /* - * Set the expiry time and activate a timer (which must previously have been - * initialised by init_timer). + * Set the expiry time and activate a timer. The timer must *previously* have + * been initialised by init_timer() (so that callback details are known). */ extern void set_timer(struct timer *timer, s_time_t expires); /* - * Deactivate a timer (which must previously have been initialised by - * init_timer). This function has no effect if the timer is not currently + * Deactivate a timer This function has no effect if the timer is not currently * active. + * The timer must *previously* have been initialised by init_timer(), or its + * structure initialised to all zeroes. */ extern void stop_timer(struct timer *timer); /* - * Migrate a timer to a different CPU. The timer must have been previously - * initialised by init_timer(). The timer may be active. + * Migrate a timer to a different CPU. The timer may be currently active. + * The timer must *previously* have been initialised by init_timer(), or its + * structure initialised to all zeroes. */ extern void migrate_timer(struct timer *timer, unsigned int new_cpu); @@ -75,11 +83,13 @@ extern void migrate_timer(struct timer *timer, unsigned int new_cpu); * Deactivate a timer and prevent it from being re-set (future calls to * set_timer will silently fail). When this function returns it is guaranteed * that the timer callback handler is not running on any CPU. + * The timer must *previously* have been initialised by init_timer(), or its + * structure initialised to all zeroes. */ extern void kill_timer(struct timer *timer); /* - * Initialisation. Must be called before any other timer function. + * Bootstrap initialisation. Must be called before any other timer function. */ extern void timer_init(void); -- 2.30.2